---
title: Report distribute
summary: Builds a report's raw XML and distributes it through clsPrint.distributeDocument.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-09-01
library: SAIF.Services.Printing
reference_type: embedded
operation_id: op-08-report-distribute
trigger: Caller invokes ReportBase.Distribute
---

# Report distribute

Builds a report's XML (if not already built) and distributes it through `clsPrint.distributeDocument`, following the same MSMQ-or-direct dispatch used by the underlying distribution operation.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-08 |
| **Trigger** | `Distribute` invoked |
| **Inputs** | `overwrite As Boolean = False`, `ReportPackage`, report XML from `Create` |
| **Outputs** | `Boolean` success |
| **Primary components** | `ReportBase.Distribute`, `Create`, `clsPrint.distributeDocument` |
| **Entry point** | `Public Function Distribute(Optional overwrite As Boolean = False) As Boolean` |

## Steps

1. If `m_reportFile Is Nothing` or `overwrite` is requested, calls `Create(overwrite)` to (re)build `m_reportXml`. This does **not** go through `Render` — there is no rendered-bytes cache check and no printer resolution here; the `m_reportFile` flag is used only as a trigger for `Create`, and `Create` does not itself populate `m_reportFile`.
2. Checks that `m_reportXml` is not `Nothing` and `ReportPackage.Length > 0` before distributing — a report can be rendered or distributed only when its XML document exists and a report package is assigned ([BR-PRT-008](../business-rules.md#br-prt-008-render-and-distribute-preconditions)).
   - If the precondition fails: `result` remains `False`, and no error is recorded.
3. Calls `xPrint.distributeDocument(ReportPackage, m_reportXml.ToString)` — note that this passes `m_reportXml.ToString` (the raw XML document's default string representation), **not** `m_reportXml.ToXpression` as `Render` does in OP-06.
   - This is a structural inconsistency*: `Distribute` does not route through the xPression-dialect serializer used elsewhere in this library, so it does not benefit from [BR-PRT-016](../business-rules.md#br-prt-016-key-propagation-for-nested-repeating-sections), [BR-PRT-017](../business-rules.md#br-prt-017-empty-value-self-closing-elements), [BR-PRT-018](../business-rules.md#br-prt-018-xml-value-escaping), or [BR-PRT-019](../business-rules.md#br-prt-019-empty-serialization-for-malformed-documents) at all.

   > **Origin**: The `distributeDocument` call is the same operation documented as [Distribute a document](op-04-distribute-a-document.md) ([BR-PRT-001](../business-rules.md#br-prt-001-package-name-extension-normalization), [BR-PRT-003](../business-rules.md#br-prt-003-synchronous-versus-queued-distribution) through [BR-PRT-006](../business-rules.md#br-prt-006-fixed-paper-tray-for-synchronous-distribution), [BR-PRT-013](../business-rules.md#br-prt-013-print-and-distribute-report-unconditional-success)).
4. Sets `result = True` on success.
5. If any exception occurs in steps 1–4, it is caught, appended to `Errors` as `New ErrorDetail("An error occurred distributing the report.", ex)`, and `result` remains `False` — the exception is never rethrown ([BR-PRT-010](../business-rules.md#br-prt-010-non-throwing-render-and-distribute-failures)).

## Process flow

```mermaid
flowchart TD
	Start([Distribute called]) --> Need{"reportFile Nothing<br>OR overwrite?"}
	Need -->|Yes| Create["Create()"]
	Need -->|No| Skip["skip create"]
	Create --> Pre{"xml set AND<br>package set?"}
	Skip --> Pre
	Pre -->|No| Fail(["Return False<br>(no error added)"])
	Pre -->|Yes| Dist["distributeDocument<br>(package, xml.ToString)<br>(→OP-04)"]
	Dist --> Ok(["Return True"])
	Create -.->|exception anywhere| Err["Add ErrorDetail"]
	Pre -.->|exception anywhere| Err
	Dist -.->|exception anywhere| Err
	Err --> Fail2(["Return False"])
```

## Failure and edge-case behavior

- Exceptions never propagate out of `Distribute`; callers must inspect `Errors` rather than rely on a thrown exception ([BR-PRT-010](../business-rules.md#br-prt-010-non-throwing-render-and-distribute-failures)) — the same non-throwing contract as [Report render lifecycle](op-06-report-render-lifecycle.md), though with a distinct error message ("An error occurred distributing the report." versus "An error occurred while rendering the report.").
- `Distribute` serializes with `.ToString` instead of `.ToXpression`, an explicit structural inconsistency* relative to OP-06/OP-11.

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Dependencies](../dependencies.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)
- [API reference](../api/index.md)

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `SAIF.Services.Printing/Reporting/ReportBase.vb`
- `SAIF.Services.Printing/Reporting/IReport.vb`